home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Complementary Applications 2004 February / SGI IRIX 6.5 Complementary Applications 2004 February.iso / dist / cde.idb / usr / dt / share / man / cat3 / pam_authenticate.z.z / pam_authenticate.z
Encoding:
Text File  |  2003-11-18  |  3.0 KB  |  98 lines
  1. .\" Sccs id goes here
  2. '\"macro stdmacro
  3. .\" Copyright (c) 1995, Sun Microsystems, Inc. 
  4. .\" All Rights Reserved
  5. .\" Don't forget to enter .IX index entries for each function.
  6. .nr X
  7. .TH pam_authenticate 3 "12 September 1995"
  8. .SH NAME
  9. pam_authenticate
  10. \- perform authentication within the PAM framework
  11.  
  12. .SH SYNOPSIS
  13. .LP
  14. .B cc
  15. .RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
  16. .B \-lpam
  17. .RI "[ " "library" " \|.\|.\|. ]"
  18. .LP
  19. .nf
  20. .ft 3
  21. #include <security/pam_appl.h>
  22. .ft
  23. .fi
  24. .LP
  25. .BI "int pam_authenticate(pam_handle_t *" "pamh" ,
  26. .BI "int " "flags");
  27. .SH DESCRIPTION
  28. .IX "pam_authenticate" "" "\fLpam_authenticate\fP \(em request authentication"
  29. .B pam_authenticate(\|)
  30. is called to authenticate the current user.
  31. The user is usually required to enter
  32. a password or similar authentication token depending upon
  33. the authentication service configured within the system.
  34. The user in question should have been specified by a prior call to
  35. .B pam_start(\|)
  36. or
  37. .B pam_set_item(\|).
  38. The following flags may be set in the
  39. .IR flags
  40. field:
  41. .RS
  42. .IP PAM_SILENT 35
  43. Authentication service should not generate any messages
  44. .IP PAM_DISALLOW_NULL_AUTHTOK 35
  45. The authentication service should return PAM_AUTH_ERROR
  46. if the user has a null authentication token
  47. .RE
  48. .SH NOTES
  49. .PP
  50. In the case of authentication failures due to an incorrect username
  51. or password, it is the responsibility of the application to retry
  52. .B pam_authenticate(\|)
  53. and to maintain the retry count.
  54. An authentication service module may implement an
  55. internal retry count and return an error
  56. PAM_MAXRETRIES
  57. if the module does not want the application to retry.
  58.  
  59. If the PAM framework can not load the authentication module, then
  60. it will return PAM_ABORT.  This indicates a serious failure and that
  61. the application should not attempt to retry the authentication.
  62.  
  63. For security reasons,
  64. the location of authentication failures is hidden from the user.  
  65. Thus, if several authentication services are stacked and a single
  66. service fails,
  67. .B pam_authenticate()
  68. requires that the user re-authenticate to all the services.
  69.  
  70. A null authentication token in the authentication database will
  71. result in successful authentication unless PAM_DISALLOW_NULL_AUTHTOK
  72. was specified. In such cases, there will not be any prompting
  73. for the user to enter an authentication token.
  74. .SH "RETURN VALUES"
  75. .PP
  76. Upon successful completion, PAM_SUCCESS is returned.
  77. In addition to the error return values described in
  78. .B pam(3),
  79. the following values may be returned:
  80. .RS
  81. .IP PAM_AUTH_ERR 29
  82. Authentication failure
  83. .IP PAM_CRED_INSUFFICIENT 29
  84. Can not access authentication data due to insufficient credentials
  85. .IP PAM_AUTHINFO_UNAVAIL 29
  86. Underlying authentication service can not retrieve authentication information
  87. .IP PAM_USER_UNKNOWN 29
  88. User not known to the underlying authentication module
  89. .IP PAM_MAXRETRIES
  90. An authentication service has maintained a retry count which
  91. has been reached. No further retries should be attempted.
  92. .RE
  93. .SH "SEE ALSO"
  94. .BR pam (3),
  95. .BR pam_start (3),
  96. .BR pam_open_session (3),
  97. .BR pam_setcred (3)
  98.